docs: Mention G_ENABLE_DIAGNOSTIC in the porting notes

Since part of our type system is resolved at run time, we need to use
run time facilities to get diagnostic messages, like deprecation
warnings for properties and signals.

We should mention the G_ENABLE_DIAGNOSTIC environment variable in the
migration guide, to let developers know how to catch deprecations and
changes while porting their code.

diff --git a/docs/reference/gtk/migrating-3to4.xml b/docs/reference/gtk/migrating-3to4.xml
index ef6fa58e013a9070dc31db5472846db0aea98109..46327e43af542f98c48cc26966a197fdadfc0351 100644 (file)
--- a/docs/reference/gtk/migrating-3to4.xml
+++ b/docs/reference/gtk/migrating-3to4.xml
@@ -52,6 +52,21 @@
       </para>
     </section>
 
+    <section>
+      <title>Enable diagnostic warnings</title>
+      <para>
+        Deprecations of properties and signals cannot be caught at compile
+        time, as both properties and signals are installed and used after
+        types have been instantiated. In order to catch deprecations and
+        changes in the run time components, you should use the
+        <envar>G_ENABLE_DIAGNOSTIC</envar> environment variable when
+        running your application, e.g.:
+        <programlisting>
+          G_ENABLE_DIAGNOSTIC=1 ./your-app
+        </programlisting>
+      </para>
+    </section>
+
     <section>
       <title>Do not use widget style properties</title>
       <para>